Skip to content

fix: keep the referenced type when a $ref has complex siblings - #1832

Open
george-oakling wants to merge 1 commit into
acacode:mainfrom
george-oakling:fix/ref-with-complex-siblings
Open

fix: keep the referenced type when a $ref has complex siblings#1832
george-oakling wants to merge 1 commit into
acacode:mainfrom
george-oakling:fix/ref-with-complex-siblings

Conversation

@george-oakling

@george-oakling george-oakling commented Sep 7, 2026

Copy link
Copy Markdown

A schema that carries a $ref next to not, allOf, oneOf or anyOf is routed to ComplexSchemaParser, which parses the complex keyword and drops the reference. With not — the one complex keyword that has no TypeScript equivalent, so NotSchemaParser returns any — the whole property collapses:

constrainedRef:
  $ref: '#/components/schemas/Status'
  not: { enum: [STATUS_UNSPECIFIED] }
// before
constrainedRef?: any;
// after
constrainedRef?: Status;

Sibling keywords beside a $ref are legal in OpenAPI 3.1, where they compose with the referenced schema. They are also what protoc-gen-connect-openapi emits for a protobuf enum field carrying a protovalidate not_in rule — the common "must not be the UNSPECIFIED member" constraint. In a 678-operation document generated that way, this turned 156 properties into any; with this change the same document generates 11, all of them genuinely dynamic (the client's own contentFormatters, a map value, google.protobuf.Any).

The fix parses the reference alongside the complex content and filters any out of the intersection, reusing the ignoreTypes idiom AllOfSchemaParser already applies. A $ref with only annotation siblings (title, description) took the primitive path and already resolved correctly; that behaviour is unchanged, and the new fixture covers all three shapes.

Tests: tests/spec/ref-with-sibling-keywords added. vitest run goes from 283 to 284 passing with no snapshot churn elsewhere; the 5 failures in paths-2 and paths-2-prefer-existing-schema-names fail identically on a clean checkout of main.


Summary by cubic

Fixes $ref schemas with complex siblings like not, allOf, oneOf, or anyOf so the referenced type is preserved instead of collapsing to any.

  • Sibling keywords are legal in OpenAPI 3.1 and are what protoc-gen-connect-openapi emits for protobuf enum fields with not_in rules.
  • The reference is now parsed alongside the complex content, and any members are filtered out of the intersection.
  • In a 678-operation generated document, this restores types on 156 properties; only genuinely dynamic fields remain any.
  • A $ref with only annotation siblings already resolved correctly and is unchanged.
  • Adds a test fixture covering plain refs, annotated refs, and refs with not.

Written for commit c3a86d4. Summary will update on new commits.

Review in cubic

A schema carrying a $ref next to `not`, `allOf`, `oneOf` or `anyOf` is routed to
the complex parser, which parses the complex keyword and drops the reference.
With `not` — the one complex keyword that cannot be expressed in TypeScript —
the property collapses to `any`:

    constrainedRef:
      $ref: '#/components/schemas/Status'
      not: { enum: [STATUS_UNSPECIFIED] }

    // before
    constrainedRef?: any;
    // after
    constrainedRef?: Status;

Sibling keywords beside a $ref are legal in OpenAPI 3.1, and are how
protoc-gen-connect-openapi renders a protobuf enum field that carries a
protovalidate `not_in` rule, so a document generated from protobuf loses the
type on every such field: 156 properties in a 678-operation document.

The reference is now parsed alongside the complex content, with `any` members
filtered out of the intersection the same way AllOfSchemaParser already does. A
$ref with only annotation siblings (title, description) was already handled and
is unchanged.
@changeset-bot

changeset-bot Bot commented Sep 7, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: c3a86d4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 4 files

Re-trigger cubic

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant